feat(timeline): kb.timeline — entity chronological trajectory (#313)#352
Open
dhgoal wants to merge 1 commit into
Open
feat(timeline): kb.timeline — entity chronological trajectory (#313)#352dhgoal wants to merge 1 commit into
dhgoal wants to merge 1 commit into
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
docs
…ev#313) read_entity returns an entity's claims as a flat set; neighbors expands graph adjacency. neither answers "what did the kb learn about this entity, in what order?". kb.timeline orders an entity's approved claims and relations along a time axis, oldest first. - order=effective uses the artifact's own created_at (accrual time); order=decided recovers approval time from the audit log's approve events (object_ids[1] -> created_at), falling back to created_at for artifacts written outside the proposal path. - since/until/types/limit filters; limit keeps the most recent n while preserving chronological order. - superseded/archived claims still appear, flagged by current status; relations carry status=null; pending proposals never appear. pure read: no propose_*, no approve, no write path is reachable — a viewport over already-reviewed artifacts. all ordering logic lives in a new timeline.py, not storage.py. registered at all four surfaces (mcp/jsonl/capabilities/cli); attaches _meta.vouch_salience when a session_id is passed, per the per-tool convention.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #313.
kb.read_entityreturns an entity and its claims as a flat set;kb.neighborsexpands graph adjacency at a point in time. neither answers "what did the kb learn about this entity, in what order?" — a trajectory. the raw material is already on disk: claims and relations carrycreated_at, and decision time is recoverable from the append-only audit log. this orders an entity's approved claims and relations along that time axis.surface
effectiveorders by the artifact's owncreated_at(when the fact entered the kb);decidedrecovers approval time from the audit log's approve events (object_ids = [proposal_id, result_id], eventcreated_at= decision time), falling back tocreated_atfor artifacts written outside the proposal path.{when, kind, id, summary, status}, oldest first (most-recent-last).statusis the claim's currentClaimStatus; a superseded/archived claim still appears, flagged. relations have no status field, sostatus = null.since/untilbound the chosen timestamp (reusingmetrics.parse_since, so iso dates and durations both work);typesfilters on claim type (fact,decision, …), relation type, or the literalclaim/relation;limitkeeps the most recent N entries, still in chronological order.list_claims/list_relations); pending proposals never appear.review gate & scope
pure read. no
propose_*, nokb.approve, no mutation — a viewport over already-reviewed artifacts, exactly likeread_entity/neighbors.tests/test_timeline.py::test_timeline_writes_nothingasserts a scoring run appends no audit event. all ordering/reconstruction logic lives in a newsrc/vouch/timeline.py;storage.pystays pure i/o. everything is local — no network.per the per-tool convention,
kb.timelineattaches the_meta.vouch_saliencesidebar inline (viasalience.attach_salience, askb_contextdoes) when asession_idis passed; it's a no-op otherwise.registered at all four sites so
test_capabilitiespasses:@mcp.tool()kb_timelineinserver.py,_h_timeline+HANDLERS["kb.timeline"]injsonl_server.py,METHODSincapabilities.py, andvouch timelineincli.py.what breaks for an existing
.vouch/nothing. purely additive read surface over already-committed artifacts.
tests
tests/test_timeline.py(15 tests): effective vs decided ordering (a claim created earliest but decided latest sorts opposite ways under the two axes), the since/until/types/limit filters, superseded-still-visible-and-flagged, entity-scoping (a second entity's claim is excluded), missing-entity and bad-order errors, the no-mutation invariant, the four-site registration, the jsonl handler, and the cli table/json/missing paths.make checkgreen (pytest, mypy, ruff).note
sibling to the open #351 (
vouch digest); the two touchcli.pyand the## [Unreleased]changelog in different spots and are independent — whichever merges first, the other rebases cleanly.